home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / Tools / vtcl / doc / CrtCommand.3 < prev    next >
Encoding:
Text File  |  1995-07-10  |  7.5 KB  |  180 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/CrtCommand.3,v 1.12 93/10/29 15:52:29 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. '\"----------------------------------------------------------------------------
  24. '\"    @(#) CrtCommand.3 27.1 93/11/04 SCOINC
  25. '\"
  26. '\"     Copyright (C) The Santa Cruz Operation, 1992-1993.
  27. '\"     This Module contains Proprietary Information of
  28. '\"    The Santa Cruz Operation, and should be treated as Confidential.
  29. '\"----------------------------------------------------------------------------
  30. .so ../man.macros
  31. .HS Tcl_CreateCommand tclc
  32. .BS
  33. .SH NAME
  34. Tcl_CreateCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo \- implement new commands in C
  35. .SH SYNOPSIS
  36. .nf
  37. \fB#include <tcl.h>\fR
  38. .sp
  39. \fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
  40. .sp
  41. int
  42. \fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
  43. .sp
  44. .VS
  45. int
  46. \fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
  47. .sp
  48. int
  49. \fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
  50. .VE
  51. .SH ARGUMENTS
  52. .AS Tcl_CmdDeleteProc **deleteProcPtr
  53. .AP Tcl_Interp *interp in
  54. Interpreter in which to create new command.
  55. .AP char *cmdName in
  56. Name of command.
  57. .AP Tcl_CmdProc *proc in
  58. Implementation of new command:  \fIproc\fR will be called whenever
  59. \fIcmdName\fR is invoked as a command.
  60. .AP ClientData clientData in
  61. Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
  62. .AP Tcl_CmdDeleteProc *deleteProc in
  63. Procedure to call before \fIcmdName\fR is deleted from the interpreter;
  64. allows for command-specific cleanup.  If NULL, then no procedure is
  65. called before the command is deleted.
  66. .AP Tcl_CmdInfo *infoPtr in/out
  67. .VS
  68. Pointer to structure containing various information about a
  69. Tcl command.
  70. .VE
  71. .BE
  72.  
  73. .SH DESCRIPTION
  74. .PP
  75. \fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
  76. it with procedure \fIproc\fR such that whenever \fIcmdName\fR is
  77. invoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
  78. will call \fIproc\fR
  79. to process the command.  If there is already a command \fIcmdName\fR
  80. associated with the interpreter, it is deleted.  \fIProc\fP should
  81. have arguments and result that match the type \fBTcl_CmdProc\fR:
  82. .nf
  83. .RS
  84. typedef int Tcl_CmdProc(
  85. .RS
  86. ClientData \fIclientData\fR,
  87. Tcl_Interp *\fIinterp\fR,
  88. int \fIargc\fR,
  89. char *\fIargv\fR[]);
  90. .RE
  91. .RE
  92. .fi
  93. When \fIproc\fR is invoked the \fIclientData\fP and \fIinterp\fR
  94. parameters will be copies of the \fIclientData\fP and \fIinterp\fR
  95. arguments given to \fBTcl_CreateCommand\fR.
  96. Typically, \fIclientData\fR points to an application-specific
  97. data structure that describes what to do when the command procedure
  98. is invoked.  \fIArgc\fR and \fIargv\fR describe the arguments to
  99. the command, \fIargc\fR giving the number of arguments (including
  100. the command name) and \fIargv\fR giving the values of the arguments
  101. as strings.  The \fIargv\fR array will contain \fIargc\fR+1 values;
  102. the first \fIargc\fR values point to the argument strings, and the
  103. last value is NULL.
  104. .PP
  105. \fIProc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR,
  106. \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.  See the Tcl overview man page
  107. for details on what these codes mean.  Most normal commands will only
  108. return \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
  109. \fIinterp->result\fR to point to a string value;
  110. in the case of a \fBTCL_OK\fR return code this gives the result
  111. of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
  112. The \fBTcl_SetResult\fR procedure provides an easy interface for setting
  113. the return value;  for complete details on how the \fIinterp->result\fR
  114. field is managed, see the \fBTcl_Interp\fR man page.
  115. Before invoking a command procedure,
  116. \fBTcl_Eval\fR sets \fIinterp->result\fR to point to an empty string, so simple
  117. commands can return an empty result by doing nothing at all.
  118. .PP
  119. .VS
  120. The contents of the \fIargv\fR array belong to Tcl and are not
  121. guaranteed to persist once \fIproc\fR returns:  \fIproc\fR should
  122. not modify them, nor should it set \fIinterp->result\fR to point
  123. anywhere within the \fIargv\fR values.
  124. Call \fBTcl_SetResult\fR with status \fBTCL_VOLATILE\fR if you want
  125. to return something from the \fIargv\fR array.
  126. .VE
  127. .PP
  128. \fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
  129. This can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
  130. or by replacing \fIcmdName\fR in another call to \fBTcl_CreateCommand\fR.
  131. \fIDeleteProc\fR is invoked before the command is deleted, and gives the
  132. application an opportunity to release any structures associated
  133. with the command.  \fIDeleteProc\fR should have arguments and
  134. result that match the type \fBTcl_CmdDeleteProc\fR:
  135. .nf
  136. .RS
  137. .sp
  138. typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
  139. .sp
  140. .RE
  141. .fi
  142. The \fIclientData\fR argument will be the same as the \fIclientData\fR
  143. argument passed to \fBTcl_CreateCommand\fR.
  144. .PP
  145. \fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
  146. Once the call completes, attempts to invoke \fIcmdName\fR in
  147. \fIinterp\fR will result in errors.
  148. If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
  149. \fBTcl_DeleteCommand\fR does nothing and returns -1;  otherwise
  150. it returns 0.
  151. There are no restrictions on \fIcmdName\fR:  it may refer to
  152. a built-in command, an application-specific command, or a Tcl procedure.
  153. .PP
  154. .VS
  155. \fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
  156. exists as a command in \fIinterp\fR.  If not then it returns 0.
  157. Otherwise it places information about the command in the structure
  158. pointed to by \fIinfoPtr\fR and returns 1.
  159. Tcl_CmdInfo structures have fields named \fIproc\fR, \fIclientData\fR,
  160. and \fIdeleteProc\fR, which have the same meaning as the corresponding
  161. arguments to \fBTcl_CreateCommand\fR.
  162. There is also a field \fIdeleteData\fR, which is the ClientData value
  163. to pass to \fIdeleteProc\fR;  it is normally the same as
  164. \fIclientData\fR but may be set independently using the
  165. \fBTcl_SetCommandInfo\fR procedure.
  166. .PP
  167. \fBTcl_SetCommandInfo\fR is used to modify the procedures and
  168. ClientData values associated with a command.
  169. Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
  170. If this command exists then \fBTcl_SetCommandInfo\fR returns 0.
  171. Otherwise, it copies the information from \fI*infoPtr\fR to
  172. Tcl's internal structure for the command and returns 1.
  173. Note that this procedure allows the ClientData for a command's
  174. deletion procedure to be given a different value than the ClientData
  175. for its command procedure.
  176. .VE
  177.  
  178. .SH KEYWORDS
  179. bind, command, create, delete, interpreter
  180.